@MichaelDeBoey Just repeating my comment here from #10913 for anyone who missed it.

We were aware of this and explored what a complete solution would look like here: #10904. We've opted instead to simplify the model and avoid this category of issue entirely.

Thanks for putting together this PR, @markdalgleish. I was thinking about this PR over the break, and it occurred to me that we could use from methods to possibly clean up the API a bit.

Instead of exporting both the header class and a parse method (e.g. AcceptEncoding and parseAcceptEncoding) we could just add a static AcceptEncoding.from(init: AcceptEncodingInit) method that would do the work the constructor is currently doing. I like this for a few reasons:

• We don't have a bunch of parse methods, instead we just export a single class for each header (and an init type)
• The parse method was always returning an instanceof its associated class, which is what from is traditionally used for in JS array methods (e.g. Array.from(), Uint8Array.from(), etc.), so this feels a little more "native"

We can also preserve the ability to pass an optional init value to the constructor by using the from() method internally if it's present.

class AcceptEncoding {
  static from(init: AcceptEncodingInit) {
    let header = new AcceptEncoding()
    // iterate over the init object and use set()/append() methods to add values...
    return header
  }

  constructor(init?: AcceptEncodingInit) {
    if (init) return AcceptEncoding.from(init)
    this.#map = new Map()
  }
}

What do you think?

@mjackson Yeah, that feels cleaner. I've pushed an update moving to this pattern.

I was using SuperHeaders to help construct responses - the API for which was very nice imo:

return new Response(buffer, new SuperHeaders({
  contentDisposition: { type: "attachment", filename },
  contentType: "application/pdf",
  cacheControl: { private: true, maxAge: 86400 }
})

Is there a way to do this after these changes? If not, what do you think about adding a util that only builds a native Headers object without being a subclass, for example:

return new Response(buffer, buildHeaders({
  contentDisposition: { type: "attachment", filename },
  contentType: "application/pdf",
  cacheControl: { private: true, maxAge: 86400 }
})

If you like the idea, I don't mind pushing a PR for review